docs: webxdc notify & privacy preserving selfAddr #90

r10s · 2024-11-19T16:36:16Z

this PR is the documentation part of the M2/M3 tasks from https://github.com/orgs/deltachat/projects/77 , currently about notify / deeplinks (click system events)

closes #89

src-docs/spec/sendUpdate.md

adbenitez · 2024-11-21T19:27:47Z

src-docs/spec/sendUpdate.md

@@ -17,6 +17,9 @@ Send an update to all peers.
       Do not add linebreaks; implementations will truncate the text at about 50 characters or less.
       If there are series of info messages, older ones may be dropped.
       use this option sparingly to not spam the chat.
+    - `update.notify`: optional array of [user addresses](./selfAddr_and_selfName.md)


to increase the usefulness of this API, would be nice if dev could pass update.notify=["all"] to avoid having to collect user IDs before being able to notify, for example a calendar app, it is good that events cause notification without the need of every user opening the app first

adbenitez · 2024-11-21T19:35:22Z

src-docs/spec/setSystemListener.md

@@ -0,0 +1,42 @@
+# setSystemListener


meta: this whole API looks a bit unnecessary, the common way to handle deep-linking in the web, and what most web apps support and web devs are used to is #hash in the URL which the web already provides APIs for accessing and parsing, and some frameworks like React with URL routing system would support and work out of the box,

on sending the update with deep-link the dev could set a update.link="#fragment" then all what the webview needs to do is to set the url to baseUrl+"#fragment" no yet another event listener, state and API to learn

this would be much easier to implement for developers, for example, to jump to a section in the HTML document when clicking the notification would require ZERO Javascript for the developer as the feature to jump to section/element ID via hash works out of the box in the web

How would you inform the app of multiple clicks (i.e. on desktop where a webxdc app runs concurrently)?
Also, if you can provide some concrete APIs for #hash in a web app, that would be nice.

How would you inform the app of multiple clicks (i.e. on desktop where a webxdc app runs concurrently)?

this works the same as it is today in web APIs, you just open the link, if the app is already in that subpage/link nothing needs to be done

Also, if you can provide some concrete APIs for #hash in a web app, that would be nice.

it is used already by apps like the public bot index, see url: https://deltachat-bot.github.io/public-bots/#/home

in that app there is a single page "#/home" but if an about page etc. is added or a category "games" to a xdc store app, etc. user could then open that link/section directly, also it is not only about fragments, that are relative links and would work for subpages ex. update.link="./scoreboard" to open a dedicated scoreboard page, which is useful for simpler apps that don't use #fragment routing like react et al.

basically real deep-linking, just linking to inside an app

https://www.geeksforgeeks.org/hashrouter-in-react-router/

in that app there is a single page "#/home" but if an about page etc. is added or a category "games" to a xdc store app, etc. user could then open that link/section directly, also it is not only about fragments, that are relative links and would work for subpages ex. update.link="./scoreboard" to open a dedicated scoreboard page, which is useful for simpler apps that don't use #fragment routing like react et al.

Are you saying that the webxdc app should be reloaded on click, but with a different path or fragment?
Is this easy to do on Android (and other platforms)?

Calling https://developer.android.com/reference/android/webkit/WebView#loadUrl(java.lang.String) or similar API should be possible on any platform.
Needs testing whether it results in full reload and losing everything if you only change the fragment.

I guess you are talking about window.location.hash -- and if a user clicks an info message, then we reset that hash? Would the running web app be able to notice that?

I like this. On iOS if you just change the hash part of a URL a webview does not reload.

Would the running web app be able to notice [the hash change]?

Yep: https://developer.mozilla.org/en-US/docs/Web/API/Window/hashchange_event

this PR adds support for the property `update.notify` to notify about changes in `update.info` or `update.summary`. the property can be set to an array of addresses [^1] core emits then the event `IncomingWebxdcNotify`, resulting in all UIs to display a system notification, maybe even via PUSH. for using the existing `update.info` and `update.summary`: the message is no secret and should be visible to all group members as usual, to not break the UX of having same group messages on all devices of all users - as known already from the normal messages. also, that way, there is no question what happens if user have disabled notifications as the change is presented in the chat as well doc counterpart at webxdc/website#90 closes #6217 [^1]: addresses come in either via the payload as currently or as an explicit sender in the future - this does not affect this PR. same for translations, see discussions at #6217 and #6097 --------- Co-authored-by: adb <asieldbenitez@gmail.com> Co-authored-by: l <link2xt@testrun.org>

hpk42 · 2024-11-22T21:18:41Z

I removed setSystemEventListener, and added an "update.href" attribute to allow a receiver to directly navigate the webxdc app to this href.

hpk42 · 2024-11-22T21:19:00Z

also refined "selfAddr" and "selfName", and added an example using them together with notify.

add `update.href` property option to update objects send via `Context::send_webxdc_status_update()`. when set together with `update.info`, UI can implement the info message as a link that is passed to the webxdc via `window.location.href`. for that purpose, UI will read the link back from `Message::get_webxdc_href()`. Practically, this allows e.g. an calendar.xdc to emits clickable update messages opening the calendar at the correct date. closes #6219 documentation at webxdc/website#90

src-docs/faq/compat.md

singpolyma · 2024-11-25T16:28:42Z

The new href idea I understand I think. But what is the notify key for?

hpk42 · 2024-11-25T18:50:50Z

The new href idea I understand I think. But what is the notify key for?

notify is for displaying a user-visible notification on the phone of (selected) receiving users .
It's for e.g. the chess-board app: when two people enter a game, then the app will send the user a notification when it's their turn. If they click the notification they go to the app, and can hit start.

…avoids snake_case and camelCase confusion :)

Co-authored-by: WofWca <wofwca@protonmail.com>

…o a dictionary and introduce a catch-all "*" key. this commit also fixes the example which is maybe a bit large now and should rather be a pointer to some actual little pseudo-chat app.

adbenitez · 2024-11-25T19:05:08Z

src-docs/spec/sendUpdate.md

+
+- `update.href`: optional string that can be passed as the navigation
+  location to the webxdc app. 
+  If specified the string must start with `#` and can not contain any


this restricts it too much and potentially make it hard for single-page apps with hash routers that want to use query part for a dialog while the hash is used for pages

I think with some examples it is good enough to avoid confusion or force to always declare the path: index.html#fragment instead of allowing sending #fragment only

link2xt · 2024-11-25T20:01:03Z

src-docs/spec/sendUpdate.md

+- `update.href`: optional string that can be passed as the navigation
+  location to the webxdc app. 
+  For now, only hash or fragment references are allowed. 
+  Strings must start with `#` and can not contain any


Now this must start with index.html#, see deltachat/deltachat-ios#2412 (comment)

src-docs/spec/selfAddr_and_selfName.md

adbenitez · 2024-11-26T01:18:32Z

src-docs/spec/sendUpdate.md

+
+- `update.info`: optional, short, informational message that will be added to the chat,
+   e.g. "Alice voted" or "Bob scored 123 in MyGame".
+   Do not add linebreaks; implementations will truncate the text at about 50 characters or less.


btw "50 character or less" for info message sounds super restrictive, some users's display name alone (ex. name and lastname) will take up most of that

src-docs/spec/sendUpdate.md

Co-authored-by: l <link2xt@testrun.org>

Add API for notifications and refined `selfAddr` and based on discussions with r10s, adb, hocuri, link2xt and others.

r10s mentioned this pull request Nov 19, 2024

feat: webxdc notify deltachat/deltachat-core-rust#6230

Merged

r10s force-pushed the webxdc-notifiy branch from 4c16be9 to 875b4d7 Compare November 19, 2024 16:59

r10s changed the title ~~docs: webxdc notify & deeplink~~ docs: webxdc notify Nov 19, 2024

r10s marked this pull request as ready for review November 19, 2024 17:18

WofWca reviewed Nov 20, 2024

View reviewed changes

src-docs/spec/sendUpdate.md Outdated Show resolved Hide resolved

r10s changed the title ~~docs: webxdc notify~~ docs: webxdc notify & system-events Nov 20, 2024

adbenitez reviewed Nov 21, 2024

View reviewed changes

r10s mentioned this pull request Nov 22, 2024

feat: update.href api deltachat/deltachat-core-rust#6248

Merged

hpk42 changed the title ~~docs: webxdc notify & system-events~~ docs: webxdc notify & privacy preserving selfAddr Nov 23, 2024

hpk42 changed the base branch from main to next-main November 23, 2024 18:38

hpk42 force-pushed the webxdc-notifiy branch from a2d69ca to bf284a1 Compare November 24, 2024 01:42

Simon-Laux reviewed Nov 24, 2024

View reviewed changes

src-docs/faq/compat.md Show resolved Hide resolved

r10s and others added 11 commits November 25, 2024 20:01

add API to notify users

9b682bb

simpler naming, matching better the density of the other items - and …

8113f98

…avoids snake_case and camelCase confusion :)

style

d6e8225

add link to selfAddr

b30cf6c

add new setSytemListener() api

3b99bc7

reword

ffc3406

Update src-docs/spec/sendUpdate.md

0b4632f

Co-authored-by: WofWca <wofwca@protonmail.com>

revise system event docs

c61bfd4

refine APIs and docs

410719b

new approach for linking removing the setSystemListener

a3b36aa

refine selfAddr

95c6831

hpk42 added 5 commits November 25, 2024 20:02

clearer structure, and a combined example

cd20d4c

streamline

f4cf982

clarify non-linkability

b7861f1

remove superflous line

863e5a0

discussed by (r10s, adb, hocuri and me): make the notify property int…

1e0a3f7

…o a dictionary and introduce a catch-all "*" key. this commit also fixes the example which is maybe a bit large now and should rather be a pointer to some actual little pseudo-chat app.

hpk42 force-pushed the webxdc-notifiy branch from f4c04db to 8f23e64 Compare November 25, 2024 19:02

adbenitez reviewed Nov 25, 2024

View reviewed changes

only allow # for now in hrefs to avoid any confusion about paths

33fa73a

hpk42 force-pushed the webxdc-notifiy branch from 8f23e64 to 33fa73a Compare November 25, 2024 19:06

link2xt reviewed Nov 25, 2024

View reviewed changes

after some more discussion with l and r10s here a new suggestion

d17d89b

hpk42 force-pushed the webxdc-notifiy branch from 0d93080 to d17d89b Compare November 25, 2024 20:10

hpk42 added 2 commits November 25, 2024 21:24

refinements

18a6c84

more href refinment

8f8904a

link2xt approved these changes Nov 25, 2024

View reviewed changes

adbenitez approved these changes Nov 26, 2024

View reviewed changes

src-docs/spec/selfAddr_and_selfName.md Outdated Show resolved Hide resolved

adbenitez reviewed Nov 26, 2024

View reviewed changes

src-docs/spec/sendUpdate.md Show resolved Hide resolved

hpk42 and others added 7 commits November 26, 2024 12:58

Update src-docs/spec/selfAddr_and_selfName.md

c289cf1

Co-authored-by: l <link2xt@testrun.org>

Update src-docs/spec/selfAddr_and_selfName.md

dfdc106

Co-authored-by: l <link2xt@testrun.org>

Update src-docs/spec/selfAddr_and_selfName.md

6b36aab

Co-authored-by: l <link2xt@testrun.org>

fix formatting strings

a15330a

formatting

f3bc50a

try to clarify linkability

68c1e42

streamlining

700d562

hpk42 merged commit 5f59743 into next-main Nov 26, 2024

hpk42 pushed a commit that referenced this pull request Dec 3, 2024

docs: webxdc notify & privacy preserving selfAddr (#90)

9d02a5b

Add API for notifications and refined `selfAddr` and based on discussions with r10s, adb, hocuri, link2xt and others.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: webxdc notify & privacy preserving selfAddr #90

docs: webxdc notify & privacy preserving selfAddr #90

r10s commented Nov 19, 2024 •

edited

Loading

adbenitez Nov 21, 2024

adbenitez Nov 21, 2024 •

edited

Loading

hpk42 Nov 22, 2024

adbenitez Nov 22, 2024 •

edited

Loading

adbenitez Nov 22, 2024 •

edited

Loading

hpk42 Nov 22, 2024

link2xt Nov 22, 2024

hpk42 Nov 22, 2024

Amzd Nov 23, 2024 •

edited

Loading

hpk42 commented Nov 22, 2024

hpk42 commented Nov 22, 2024

singpolyma commented Nov 25, 2024

hpk42 commented Nov 25, 2024

adbenitez Nov 25, 2024

adbenitez Nov 25, 2024

link2xt Nov 25, 2024

adbenitez Nov 26, 2024

docs: webxdc notify & privacy preserving selfAddr #90

docs: webxdc notify & privacy preserving selfAddr #90

Conversation

r10s commented Nov 19, 2024 • edited Loading

Choose a reason for hiding this comment

adbenitez Nov 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adbenitez Nov 22, 2024 • edited Loading

Choose a reason for hiding this comment

adbenitez Nov 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Amzd Nov 23, 2024 • edited Loading

Choose a reason for hiding this comment

hpk42 commented Nov 22, 2024

hpk42 commented Nov 22, 2024

singpolyma commented Nov 25, 2024

hpk42 commented Nov 25, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

r10s commented Nov 19, 2024 •

edited

Loading

adbenitez Nov 21, 2024 •

edited

Loading

adbenitez Nov 22, 2024 •

edited

Loading

adbenitez Nov 22, 2024 •

edited

Loading

Amzd Nov 23, 2024 •

edited

Loading